@turf/helpers
Advanced tools
The @turf/helpers package is part of the Turf.js library, which is a modular geospatial engine written in JavaScript. It provides functions to create various simple geometrical features such as points, lines, and polygons, and to manipulate these geometries in various ways. This package is particularly useful for developers working with geographic information systems (GIS) and spatial analysis in web applications.
Creating Points
This function creates a GeoJSON Point feature using the provided coordinates. It is useful for representing locations on a map.
const point = turf.point([5, 10]);Creating LineStrings
This function creates a GeoJSON LineString feature from an array of positions. It is useful for mapping routes or paths.
const line = turf.lineString([[5, 10], [20, 40]]);Creating Polygons
This function creates a GeoJSON Polygon feature from an array of linear rings. It is used to represent areas such as city boundaries or lakes.
const polygon = turf.polygon([[[5, 10], [20, 40], [40, 0], [5, 10]]]);Leaflet is a leading open-source JavaScript library for mobile-friendly interactive maps. While Leaflet itself focuses more on map interactions and overlays, it can be used in conjunction with other tools for creating and manipulating geographic data, similar to @turf/helpers.
OpenLayers is another powerful open-source JavaScript library that handles various map-related tasks. It provides more comprehensive features for handling complex spatial operations compared to @turf/helpers, which is more focused on creating and manipulating simple geometrical features.
Linear measurement units.
⚠️ Warning. Be aware of the implications of using radian or degree units to measure distance. The distance represented by a degree of longitude varies depending on latitude.
See https://www.thoughtco.com/degree-of-latitude-and-longitude-distance-4070616 for an illustration of this behaviour.
Type: ("meters" | "metres" | "millimeters" | "millimetres" | "centimeters" | "centimetres" | "kilometers" | "kilometres" | "miles" | "nauticalmiles" | "inches" | "yards" | "feet" | "radians" | "degrees")
Area measurement units.
Type: (Exclude<Units, ("radians" | "degrees")> | "acres" | "hectares")
Grid types.
Type: ("point" | "square" | "hex" | "triangle")
Shorthand corner identifiers.
Type: ("sw" | "se" | "nw" | "ne" | "center" | "centroid")
Geometries made up of lines i.e. lines and polygons.
Type: (LineString | MultiLineString | Polygon | MultiPolygon)
Convenience type for all possible GeoJSON.
Type: (Feature | FeatureCollection | Geometry | GeometryCollection)
The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The mean radius was selected because it is recommended by the Haversine formula (used by turf/distance) to reduce error.
Type: number
Unit of measurement factors based on earthRadius.
Keys are the name of the unit, values are the number of that unit in a single radian
Area of measurement factors based on 1 square meter.
Type: Record<AreaUnits, number>
Wraps a GeoJSON Geometry in a GeoJSON Feature.
geom (G | null)
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featuregeometry GeometryObject input geometry
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};
var feature = turf.feature(geometry);
//=feature
Returns Feature<GeometryObject, GeoJsonProperties> a GeoJSON Feature
Creates a GeoJSON Geometry from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection
type ("Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon") Geometry Typecoordinates Array<any> Coordinates_options Record<string, never> (optional, default {})options Object Optional Parameters (optional, default {})var type = "Point";
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
// => geometry
Returns Geometry a GeoJSON Geometry
Creates a Point Feature from a Position.
coordinates Position longitude, latitude position (each in decimal degrees)
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar point = turf.point([-75.343, 39.984]);
//=point
Returns Feature<Point, GeoJsonProperties> a Point feature
Creates a Point FeatureCollection from an Array of Point coordinates.
properties GeoJsonProperties Translate these properties to each Feature (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north]
associated with the FeatureCollectionoptions.id Id? Identifier associated with the FeatureCollectionvar points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);
//=points
Returns FeatureCollection<Point> Point Feature
Creates a Polygon Feature from an Array of LinearRings.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });
//=polygon
Returns Feature<Polygon, GeoJsonProperties> Polygon Feature
Creates a Polygon FeatureCollection from an Array of Polygon coordinates.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the FeatureCollectionvar polygons = turf.polygons([
[[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]],
[[[-15, 42], [-14, 46], [-12, 41], [-17, 44], [-15, 42]]],
]);
//=polygons
Returns FeatureCollection<Polygon, GeoJsonProperties> Polygon FeatureCollection
Creates a LineString Feature from an Array of Positions.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar linestring1 = turf.lineString([[-24, 63], [-23, 60], [-25, 65], [-20, 69]], {name: 'line 1'});
var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], {name: 'line 2'});
//=linestring1
//=linestring2
Returns Feature<LineString, GeoJsonProperties> LineString Feature
Creates a LineString FeatureCollection from an Array of LineString coordinates.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north]
associated with the FeatureCollectionoptions.id Id? Identifier associated with the FeatureCollectionvar linestrings = turf.lineStrings([
[[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
[[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
]);
//=linestrings
Returns FeatureCollection<LineString, GeoJsonProperties> LineString FeatureCollection
Takes one or more Features and creates a FeatureCollection.
features Array<Feature<GeometryObject, GeoJsonProperties>> input features
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar locationA = turf.point([-75.343, 39.984], {name: 'Location A'});
var locationB = turf.point([-75.833, 39.284], {name: 'Location B'});
var locationC = turf.point([-75.534, 39.123], {name: 'Location C'});
var collection = turf.featureCollection([
locationA,
locationB,
locationC
]);
//=collection
Returns FeatureCollection<GeometryObject, GeoJsonProperties> FeatureCollection of Features
Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar multiLine = turf.multiLineString([[[0,0],[10,10]]]);
//=multiLine
Returns Feature<MultiLineString, GeoJsonProperties> a MultiLineString feature
Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar multiPt = turf.multiPoint([[0,0],[10,10]]);
//=multiPt
Returns Feature<MultiPoint, GeoJsonProperties> a MultiPoint feature
Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
//=multiPoly
Returns Feature<MultiPolygon, GeoJsonProperties> a multipolygon feature
Creates a Feature based on a coordinate array. Properties can be added optionally.
geometries Array<(Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon)> an array of GeoJSON Geometries
properties GeoJsonProperties an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
options.bbox BBox? Bounding Box Array [west, south, east, north] associated with the Featureoptions.id Id? Identifier associated with the Featurevar pt = turf.geometry("Point", [100, 0]);
var line = turf.geometry("LineString", [[101, 0], [102, 1]]);
var collection = turf.geometryCollection([pt, line]);
// => collection
Returns Feature<GeometryCollection, GeoJsonProperties> a GeoJSON GeometryCollection Feature
Round number to precision
turf.round(120.4321)
//=120
turf.round(120.4321, 2)
//=120.43
Returns number rounded number
Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
radians number in radians across the sphereunits Units can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")Returns number distance
Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
distance number in real unitsunits Units can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")Returns number radians
Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
distance number in real unitsunits Units can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")Returns number degrees
Converts any bearing angle from the north line direction (positive clockwise) and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line
bearing number angle, between -180 and +180 degreesReturns number angle between 0 and 360 degrees
Converts any azimuth angle from the north line direction (positive clockwise) and returns an angle between -180 and +180 degrees (positive clockwise), 0 being the north line
angle number between 0 and 360 degreesReturns number bearing between -180 and +180 degrees
Converts an angle in radians to degrees
radians number angle in radiansReturns number degrees between 0 and 360 degrees
Converts an angle in degrees to radians
degrees number angle between 0 and 360 degreesReturns number angle in radians
Converts a length from one unit to another.
length number Length to be convertedoriginalUnit Units Input length unit (optional, default "kilometers")finalUnit Units Returned length unit (optional, default "kilometers")Returns number The converted length
Converts an area from one unit to another.
area number Area to be convertedoriginalUnit AreaUnits Input area unit (optional, default "meters")finalUnit AreaUnits Returned area unit (optional, default "kilometers")Returns number The converted length
isNumber
num any Number to validateturf.isNumber(123)
//=true
turf.isNumber('foo')
//=false
Returns boolean true/false
isObject
input any variable to validateturf.isObject({elevation: 10})
//=true
turf.isObject('foo')
//=false
Returns boolean true/false, including false for Arrays and Functions
This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.
Install this single module individually:
$ npm install @turf/helpers
Or install the all-encompassing @turf/turf module that includes all modules as functions:
$ npm install @turf/turf
FAQs
turf helpers module
The npm package @turf/helpers receives a total of 3,199,704 weekly downloads. As such, @turf/helpers popularity was classified as popular.
We found that @turf/helpers demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.
Research
Security News
Malicious npm package postcss-optimizer delivers BeaverTail malware, targeting developer systems; similarities to past campaigns suggest a North Korean connection.